Make the keybindings menu's Lua bind scan safe against load-time config reads - #7564

Ran into this exact issue after upgrading to Quattro 4.0
Pressing SUPER + K pegged a background lua process at 100% CPU because my monitors.lua iterates over hl.get_monitors() with ipairs.

Tested this fix locally; it resolves the infinite loop cleanly and makes the keybindings scan instantaneous. Hope to see this merged soon!

Confirming on omarchy 4.0.3-1 (Hyprland 0.56.2, Lua 5.5.1): a personal module that
iterated hl.get_windows() at require time hung the scan, and repeated Super+K presses
left eight orphaned lua processes at 100% CPU each for over six hours. The timeout in
this PR is the part that would have contained that; the stub fix removes the trigger.

Confirming another real-world manifestation of this on 4.0.0.r2147.g2fbac0c-1 — this one doesn't just drop a bind from the menu, it makes the menu launch the wrong app.

I have flea set as my default file manager. Its installer (flea --default) correctly unbinds and rewrites SUPER+SHIFT+F in ~/.config/hypr/bindings.lua:

o.bind("SUPER + SHIFT + F", "File manager", { launch = 'flea --gui' })

Pressing SUPER+SHIFT+F directly opens flea correctly (hyprctl binds shows the live dispatcher resolving as expected). But selecting the same "File manager" row from the SUPER+K search menu opens Nautilus instead.

Root cause is this PR's diagnosis exactly: hyprland.lua loads default.hypr.omarchy (which pulls in default/hypr/qconsole.lua) before hypr.bindings (the user's own overrides). The scan crashes inside qconsole.lua — same attempt to compare number with table on a monitor.scale > 0 check, now at line 123 rather than 64, so the line's moved but the bug hasn't:

$ DEBUG=1 omarchy-menu-keybindings
[DEBUG] lua bind scan failed: /usr/share/omarchy/default/hypr/qconsole.lua:123: attempt to compare number with table

Because the crash happens before hypr.bindings is ever reached, the scan's cache keeps the stale default from default/hypr/bindings/applications.lua:

$ lua <extracted scan snippet>
65      File manager    F       exec    omarchy-launch-nautilus
73      File manager (cwd)      F       exec    omarchy-launch-nautilus-cwd

...instead of the user's actual flea --gui override. So it's not just that entries silently go missing — for anyone who has overridden a default Omarchy keybind, the search menu can confidently dispatch the old action while the real key combo does the right thing. Would be good to land this fix; the noop stub degrading harmlessly under comparison (not just under ipairs/length) directly fixes this case too.

Reviewed and reproduced on a worker built from the Omarchy ISO, with the stock config plus a user o.rebind("SUPER + SHIFT + F", "File manager", { launch = "flea" }) and, separately, an ipairs(hl.get_monitors()) loop:

• On quattro the scan aborts at default/hypr/qconsole.lua:123 and the menu's File manager row dispatches omarchy-launch-nautilus; the loop hangs the menu until killed.
• On this branch the row dispatches flea and the loop returns at once. With the stub changes reverted, both failures come back. A config stuck in while true do end now ends at the 10 s timeout and leaves no lua behind.
• test/shell.d/menu-keybindings-lua-scan-test.sh passes 3/3 here and fails on quattro; test/shell.d/keybindings-menu-test.sh passes 16/16. ./test/cli stops at "vscode generated theme references current theme file" on this branch and on quattro alike, so that failure is not this change's, but it does mean the rest of that suite did not run.

I pushed two commits to the branch. The first merges quattro, which had moved the cache version to v14. The second bumps the version to v15. The records cache is keyed only on that version, the keymap and hyprctl binds, so without the bump anyone already holding a cache from the broken scan keeps getting the stale default after this lands. I confirmed that on the worker: a v14 cache written by quattro kept dispatching nautilus until the bump.

Six other open pull requests fix parts of the same bug: #8876, #12712, #12916, #13276, #12155 and #11733. This one fixes both the endless loop and the qconsole abort, and it has a test that fails without the fix. #12712, #12916 and #12155 do not get past qconsole. #8876 gets past it by returning nil monitors, which still breaks a config that reads a field off one. #13276 has no test. #11733 is a redesign that would need its own review.

Second opinion from Codex Medium, which agreed with that choice and with the cache bump (its independence from this review is not guaranteed). It also raised two design points that I have not changed, because they are a call about how far the stub should pretend:

• A scan cut off by the timeout is cached like a finished one, so its partial records stay until the binds change. A scan that errors partway is already cached the same way.
• Because comparisons, arithmetic and concatenation on stub values now return made-up results, a config that guards a comparison with pcall, or builds a command from a monitor field, can take a different branch or record a truncated command where the scan used to stop.

This links #7025, #12052 and #12124, which it fixes. The next step is the maintainer's.

Merged this with #12557 locally and measured it, because the two edit the same scan and are textually compatible while being behaviourally incompatible. git merge-tree reports no conflict, and the merged tree fails one test from each side.

#12557 adds an id column to the scan's output, inserted as field 3, so a row that read modmask description key kind arg reads modmask description id key kind arg. That breaks the two fixed-string assertions in menu-keybindings-lua-scan-test.sh:52-53, which pin the five-field layout:

expected: 64	Keybindings menu	K	exec	omarchy-menu keybindings
actual:   64	Keybindings menu	Keybindings menu	K	exec	omarchy-menu keybindings

In the other direction, this PR rewrites the heredoc to timeout 10 lua <<'LUA', and #12557's hyprland-bind-id-test.sh extracts the scan by matching that line exactly, so on the merge the extraction returns nothing and the five assertions that read scan output go with it.

On the merge: menu-keybindings-lua-scan-test.sh 1 ok and 1 not ok, hyprland-bind-id-test.sh 4 ok and 1 not ok, keybindings-menu-test.sh unaffected at 16/16. Both breakages are a one-line fix in whichever PR lands second, and I will make them on my side if this one lands first. Writing it down because the repo has no CI, so nothing would surface it before a merge.

Separately, as the author of one of the seven PRs touching this scan: this is the only one of them whose test fails on quattro and passes on the branch, which is the property that makes a fix here checkable later. The timeout matters for a reason the other candidates cannot cover either, since a stub that degrades comparisons can still be sent into a loop by a config that iterates on a condition.

TL;DR: This fixes the reported scan failure. One optional follow-up for custom configs: a type error in monitors.lua can still prevent bindings.lua from loading. Catching each require separately preserves later binds; the two tests below cover a numeric format and direct monitor indexing. This need not hold up the shipped-config fix.

local m = hl.get_active_monitor()
string.format("%dx%d@%d", m.width, m.height, m.refresh_rate)   -- bad argument #2 to 'format'
math.floor(m.width)                                            -- bad argument #1 to 'floor'
if tonumber(m.scale) > 1 then end                              -- tonumber(stub) is nil
string.lower(m.name)                                           -- bad argument #1 to 'lower'
for x = 0, m.width, 960 do end                                 -- 'for' limit must be a number
local gaps = hl.get_config("general.gaps_out") * 2             -- the stub's get_config returns nil

local first = hl.get_monitors()[1]
hl.monitor({ output = first.name })   -- attempt to index a nil value (local 'first')

-- Load each module under its own pcall, so a module that still cannot run
-- against the stub costs only its own binds, not every bind loaded after it
-- (the user's hypr.bindings is required after hypr.monitors and hypr.input).
local load_module = require
require = function(name)
  local ok, result = pcall(load_module, name)
  if ok then
    return result
  end

  if os.getenv("DEBUG") == "1" then
    io.stderr:write("[DEBUG] lua bind scan skipped " .. tostring(name) .. ": " .. tostring(result) .. "\n")
  end

  return noop
end

# The user's hypr.bindings loads after hypr.monitors and hypr.input, so a
# module the stub still cannot run must cost only its own binds, not every
# bind loaded after it.
mkdir -p "$TMPDIR/later/.config/hypr"
cat >"$TMPDIR/later/.config/hypr/hyprland.lua" <<'LUA'
package.path = os.getenv("HOME") .. "/.config/?.lua;" .. package.path
require("hypr.monitors")
require("hypr.bindings")
LUA
cat >"$TMPDIR/later/.config/hypr/monitors.lua" <<'LUA'
local monitor = hl.get_active_monitor()
hl.monitor({ output = monitor.name, mode = string.format("%dx%d", monitor.width, monitor.height) })
LUA
cat >"$TMPDIR/later/.config/hypr/bindings.lua" <<'LUA'
hl.bind("SUPER + RETURN", hl.dsp.exec_cmd("alacritty"), { description = "Terminal" })
LUA

output=$(HOME="$TMPDIR/later" timeout 10 lua - <<<"$scan" 2>&1)
grep -qF $'64\tTerminal\tRETURN\texec\talacritty' <<<"$output" ||
  fail "a module the stub cannot run does not drop the binds loaded after it (got: $output)"
pass "a module the stub cannot run does not drop the binds loaded after it"

# A stub list answers nil for [1] so ipairs ends; taking the first element
# directly must not cost the binds loaded later either.
cat >"$TMPDIR/later/.config/hypr/monitors.lua" <<'LUA'
local first = hl.get_monitors()[1]
hl.monitor({ output = first.name })
LUA

output=$(HOME="$TMPDIR/later" timeout 10 lua - <<<"$scan" 2>&1)
grep -qF $'64\tTerminal\tRETURN\texec\talacritty' <<<"$output" ||
  fail "indexing the first element of a stub list does not drop the binds loaded after it (got: $output)"
pass "indexing the first element of a stub list does not drop the binds loaded after it"

Thanks @tobi for the fix and the clear write-up. The worker run by @omarchybot and @linyiru's #12557 note here, and on #13276 @llstrk's review and @KewkLW's merge-order note, already cover the rest, so I haven't repeated them.

Independent verification: the evidence for this PR comes from a full proof audit of 7b49d0b merged onto quattro at 035ce29 (evaluated merge e1ff55c): test report 69 passed · 0 failed · 0 skipped. Rechecked on quattro b83d3df (2026-10-08): the scan script is unchanged but the shipped Hyprland Lua configuration changed, and rerunning this head merged onto that tip preserves the first table's results and the remaining custom-monitor aborts. Checked by running the scan from each tree; not a formal proof.

This now conflicts with quattro: e1b0e5e (#14431) changed the scan's line to lua -E - <<'LUA'. I rebased it locally onto quattro (4c1b4cb), keeping both changes: timeout 10 lua -E - <<'LUA'. Two lines of menu-keybindings-lua-scan-test.sh then need to follow, because they match the old line literally:

-scan=$(awk '/lua <<.LUA.$/ { capture = 1; next } /^LUA$/ { capture = 0 } capture' "$script")
+scan=$(awk '/lua (-E - )?<<.LUA.$/ { capture = 1; next } /^LUA$/ { capture = 0 } capture' "$script")
...
-grep -q "timeout 10 lua <<'LUA'" "$script" || fail "Lua bind scan is time-boxed"
+grep -q "timeout 10 lua -E - <<'LUA'" "$script" || fail "Lua bind scan is time-boxed"

With that, menu-keybindings-lua-scan-test.sh passes 3/3, keybindings-menu-test.sh and ./test/cli pass. In the sandbox matrix from earlier, the rebased tree also handles the new report #15216 (a toggle walking hl.get_windows() at load, which hangs v4.0.4) and a floating workspace-layout default (workspace-modes.lua walks windows at load). In all four scenarios it returns in ~50 ms with user binds dispatchable.

Rebased again onto current quattro (84cfb93). #15326 added a second conflict in bin/omarchy-menu-keybindings, in the cache key. Keeping quattro's side there (v16 plus the language lines) and timeout 10 lua -E - for the scan, plus the two test lines from my last comment, menu-keybindings-lua-scan-test.sh passes 3/3. keybindings-menu-test.sh gives the same result as on quattro.

One more case this fixes: #14482 and #15263 added default/hypr/workspace-modes.lua, which runs at config load (through default.hypr.toggles) and walks ipairs(hl.get_windows()) once a workspace is saved as floating with Super + L. I scanned a config that loads only the toggles, with one saved floating workspace. On quattro the scan never finishes (killed at an 8 s limit); on the rebased branch it completes and reports the binds declared after it. With the shipped config, quattro still aborts earlier in qconsole.lua, so this hang is hidden today. But a fix that gets past qconsole without ending ipairs would expose it to everyone using floating workspaces.

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues remain.

Summary

Makes the keybindings scan survive load-time reads of Hyprland state.

• The keybindings menu can scan Lua binds without getting stuck.

The earlier Lua-environment concern is addressed: both standalone scan runs now use lua -E -. No new actionable issues were found.

_{Reviews (3) · Last reviewed commit: "Check the bind scan finishes without a w..." · Reviewed by Greptile}

This conflicted with quattro, so I merged quattro (246f33a) into the branch and pushed it as 25a1cbe. The scan now runs as timeout 10 lua -E -, which keeps the -E from #14431. The cache version moves to v18 because quattro is already at v17, so caches written by the broken scan are still rescanned. menu-keybindings-lua-scan-test.sh now extracts and checks the new line, as @aholbreich described above.

I checked the new head on a worker built from the Omarchy ISO, using its stock config:

• With a user o.rebind("SUPER + SHIFT + F", "File manager", { launch = "flea" }), quattro's scan aborts at default/hypr/qconsole.lua:123, so the menu's File manager row runs omarchy-launch-nautilus. On this branch the row runs flea. With the stub changes reverted, it runs nautilus again.
• An ipairs(hl.get_monitors()) loop before the defaults load hangs quattro until it is killed. On this branch the menu returns in 0.4 s.
• A config stuck in while true do end stops at the 10 s limit. Its result is cached, and no lua is left running.
• menu-keybindings-lua-scan-test.sh passes 3/3 here, and fails on quattro and with the stub reverted. keybindings-menu-test.sh passes 20/20 and menu-keybindings-key-names-test.sh 3/3. ./test/cli passes, and CI is green.

#14128 does not cache a scan that its loop guard stopped. I considered bringing that here for the timeout and left it out. With it, a config that hangs under the stub costs about 20 s on every SUPER+K (measured on the worker): the result is never cached, and a failed cache write makes the menu scan a second time. Such a hang happens the same way on every scan, so scanning again finds nothing new. Without it, the hang costs 10 s once and the partial result is cached, which is how a scan that errors part way is already treated.

Other open fixes for this bug: #12712 ends the ipairs loop but still aborts at the qconsole.lua comparison, so a user's rebinds still run the default action. #13276 makes nearly the same stub change, with no time limit and no test. #14128 is the change above. This one is the oldest, and the only one that fixes both the hang and the abort. #13276 also handles bitwise operators on stub values, which this does not; no report has hit that case.

I had Codex Medium give a second opinion. It found no defects in the merge. On the timeout question it reached the same conclusion, but my brief had already pointed at the second scan, so that agreement is not independent. Comparing the four diffs, it also picked this one.

This waits on the maintainer: #12712 already carries ready, so this one is labelled verified and not ready. Which of the two lands is the maintainer's call.

I pushed three commits to this branch (now b1ac64e). They bring in the best parts of two later fixes for the same hang, with their authors credited as co-authors:

• From Fix Super+K hang when config iterates hl.get_workspaces() #14128 (@AnPod): the scan now runs under an instruction-count hook, so a config that loops in a way the stub cannot end stops after 50M instructions instead of holding the menu for the full 10 s. On a worker, a while true do end config returns in 0.29 s instead of 10.0 s, and the bind declared before the loop is still reported. The stock config needs about 69k instructions, and it scans to the same 234 binds with or without the hook. timeout 10 stays as the backstop for what the hook cannot reach: a loop inside a coroutine, or a config that catches the error and keeps going. A scan the hook stops is cached like one that errors part way. That is the one part of Fix Super+K hang when config iterates hl.get_workspaces() #14128 I left out, for the reason in my last comment: the same config would just stop again on the next SUPER+K.
• From End the bind scan's stub window list instead of looping on it #15308 (@nekomario28): an end-to-end test in keybindings-menu-test.sh. It puts an ipairs(hl.get_windows()) walk ahead of the stock config, runs the whole menu under a timeout and checks that the Lua-only Terminal bind still resolves.
• menu-keybindings-lua-scan-test.sh now runs the scan with lua -E, as the menu does, which Greptile pointed out. Without it, a LUA_INIT or LUA_PATH in the tester's environment could fail the test. A new test there checks that the runaway config above stops early and keeps its binds.

What ran, on a worker built from the Omarchy ISO: the scan test and the window-walk test both fail on quattro (cce8b1c) and with the stub change reverted, and the runaway test fails without the hook. On this head, menu-keybindings-lua-scan-test.sh passes 4/4, keybindings-menu-test.sh 21/21, menu-keybindings-key-names-test.sh 3/3, and ./test/cli passes.

Codex Medium reviewed the three commits over two rounds. It found no defects in the code. In the first round it pointed out wording in the commits that claimed more than was shown: a general speed claim, and a test described as proving the whole scan finished. It also raised the coroutine case. All of that is corrected in what I pushed, and its second round was clean. It can read this session's notes, so where it agrees with me, that agreement isn't guaranteed to be independent.

This is labelled verified at the new head. It still waits on the maintainer, because #12712 carries ready for the same bug and only one of the two should land.

I pushed one commit to this branch (now 3deb771). It brings in the test approach from #15704, with @dmkenney credited as co-author: the scan tests no longer use a wall-clock budget.

Before this, menu-keybindings-lua-scan-test.sh failed any scan that took 5 s or more, which a slow or busy machine can hit with nothing wrong. A scan that never ends is still caught, by its exit status instead of the clock. Run directly, a hung scan is killed by the test's timeout 60 and the test fails. Run through the menu, the menu's own timeout 10 stops it before the Terminal bind that keybindings-menu-test.sh looks for. The outer timeouts went from 10 s to 60 s, so only a real hang reaches them. The code in bin/ did not change.

What ran, on a worker built from the Omarchy ISO, against current quattro (4e059ac):

• With this pull request's tests, the scan test and the window-walk test both fail on quattro, and both fail with the bin/ change reverted.
• With only the instruction-count hook removed, the runaway test still fails. It waits out the 60 s timeout and fails on the exit status, so the hook stays covered without a clock.
• On this head, menu-keybindings-lua-scan-test.sh passes 4/4, keybindings-menu-test.sh 21/21 and menu-keybindings-key-names-test.sh 3/3, and ./test/cli passes. All of that holds again with the head merged with current quattro, which merges cleanly.

Codex Medium reviewed the new commit and found no defects. It confirmed that both regression cases still fail when what they guard is broken. It noted that the only thing the old checks proved and these do not is finishing within 5 s on the test machine, which is the budget this change removes on purpose. It can read this session's notes, so where it agrees with me, that agreement isn't guaranteed to be independent.

This is verified at the new head. It is not marked ready, because #12712 carries ready for the same bug, and only one of the two should land. On current quattro, #12712 still stops the scan at qconsole.lua:123, and this pull request does not. Choosing between them is the maintainer's call, and that is what this waits on.